<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- Copyright © 1988-2023 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Funding Free Software", the Front-Cover
Texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
"GNU Free Documentation License".

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development. -->
<title>Scalar Return (GNU Compiler Collection (GCC) Internals)</title>

<meta name="description" content="Scalar Return (GNU Compiler Collection (GCC) Internals)">
<meta name="keywords" content="Scalar Return (GNU Compiler Collection (GCC) Internals)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">

<link href="index.html" rel="start" title="Top">
<link href="Option-Index.html" rel="index" title="Option Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Stack-and-Calling.html" rel="up" title="Stack and Calling">
<link href="Aggregate-Return.html" rel="next" title="Aggregate Return">
<link href="Register-Arguments.html" rel="prev" title="Register Arguments">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>


</head>

<body lang="en">
<div class="subsection-level-extent" id="Scalar-Return">
<div class="nav-panel">
<p>
Next: <a href="Aggregate-Return.html" accesskey="n" rel="next">How Large Values Are Returned</a>, Previous: <a href="Register-Arguments.html" accesskey="p" rel="prev">Passing Arguments in Registers</a>, Up: <a href="Stack-and-Calling.html" accesskey="u" rel="up">Stack Layout and Calling Conventions</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h4 class="subsection" id="How-Scalar-Function-Values-Are-Returned"><span>18.9.8 How Scalar Function Values Are Returned<a class="copiable-link" href="#How-Scalar-Function-Values-Are-Returned"> &para;</a></span></h4>
<a class="index-entry-id" id="index-return-values-in-registers"></a>
<a class="index-entry-id" id="index-values_002c-returned-by-functions"></a>
<a class="index-entry-id" id="index-scalars_002c-returned-as-values"></a>

<p>This section discusses the macros that control returning scalars as
values&mdash;values that can fit in registers.
</p>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fFUNCTION_005fVALUE"><span class="category-def">Target Hook: </span><span><code class="def-type">rtx</code> <strong class="def-name">TARGET_FUNCTION_VALUE</strong> <code class="def-code-arguments">(const_tree <var class="var">ret_type</var>, const_tree <var class="var">fn_decl_or_type</var>, bool <var class="var">outgoing</var>)</code><a class="copiable-link" href="#index-TARGET_005fFUNCTION_005fVALUE"> &para;</a></span></dt>
<dd>
<p>Define this to return an RTX representing the place where a function
returns or receives a value of data type <var class="var">ret_type</var>, a tree node
representing a data type.  <var class="var">fn_decl_or_type</var> is a tree node
representing <code class="code">FUNCTION_DECL</code> or <code class="code">FUNCTION_TYPE</code> of a
function being called.  If <var class="var">outgoing</var> is false, the hook should
compute the register in which the caller will see the return value.
Otherwise, the hook should return an RTX representing the place where
a function returns a value.
</p>
<p>On many machines, only <code class="code">TYPE_MODE (<var class="var">ret_type</var>)</code> is relevant.
(Actually, on most machines, scalar values are returned in the same
place regardless of mode.)  The value of the expression is usually a
<code class="code">reg</code> RTX for the hard register where the return value is stored.
The value can also be a <code class="code">parallel</code> RTX, if the return value is in
multiple places.  See <code class="code">TARGET_FUNCTION_ARG</code> for an explanation of the
<code class="code">parallel</code> form.   Note that the callee will populate every
location specified in the <code class="code">parallel</code>, but if the first element of
the <code class="code">parallel</code> contains the whole return value, callers will use
that element as the canonical location and ignore the others.  The m68k
port uses this type of <code class="code">parallel</code> to return pointers in both
&lsquo;<samp class="samp">%a0</samp>&rsquo; (the canonical location) and &lsquo;<samp class="samp">%d0</samp>&rsquo;.
</p>
<p>If <code class="code">TARGET_PROMOTE_FUNCTION_RETURN</code> returns true, you must apply
the same promotion rules specified in <code class="code">PROMOTE_MODE</code> if
<var class="var">valtype</var> is a scalar type.
</p>
<p>If the precise function being called is known, <var class="var">func</var> is a tree
node (<code class="code">FUNCTION_DECL</code>) for it; otherwise, <var class="var">func</var> is a null
pointer.  This makes it possible to use a different value-returning
convention for specific functions when all their calls are
known.
</p>
<p>Some target machines have &ldquo;register windows&rdquo; so that the register in
which a function returns its value is not the same as the one in which
the caller sees the value.  For such machines, you should return
different RTX depending on <var class="var">outgoing</var>.
</p>
<p><code class="code">TARGET_FUNCTION_VALUE</code> is not used for return values with
aggregate data types, because these are returned in another way.  See
<code class="code">TARGET_STRUCT_VALUE_RTX</code> and related macros, below.
</p></dd></dl>

<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-FUNCTION_005fVALUE"><span class="category-def">Macro: </span><span><strong class="def-name">FUNCTION_VALUE</strong> <var class="def-var-arguments">(<var class="var">valtype</var>, <var class="var">func</var>)</var><a class="copiable-link" href="#index-FUNCTION_005fVALUE"> &para;</a></span></dt>
<dd><p>This macro has been deprecated.  Use <code class="code">TARGET_FUNCTION_VALUE</code> for
a new target instead.
</p></dd></dl>

<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-LIBCALL_005fVALUE"><span class="category-def">Macro: </span><span><strong class="def-name">LIBCALL_VALUE</strong> <var class="def-var-arguments">(<var class="var">mode</var>)</var><a class="copiable-link" href="#index-LIBCALL_005fVALUE"> &para;</a></span></dt>
<dd><p>A C expression to create an RTX representing the place where a library
function returns a value of mode <var class="var">mode</var>.
</p>
<p>Note that &ldquo;library function&rdquo; in this context means a compiler
support routine, used to perform arithmetic, whose name is known
specially by the compiler and was not mentioned in the C code being
compiled.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fLIBCALL_005fVALUE"><span class="category-def">Target Hook: </span><span><code class="def-type">rtx</code> <strong class="def-name">TARGET_LIBCALL_VALUE</strong> <code class="def-code-arguments">(machine_mode <var class="var">mode</var>, const_rtx <var class="var">fun</var>)</code><a class="copiable-link" href="#index-TARGET_005fLIBCALL_005fVALUE"> &para;</a></span></dt>
<dd><p>Define this hook if the back-end needs to know the name of the libcall
function in order to determine where the result should be returned.
</p>
<p>The mode of the result is given by <var class="var">mode</var> and the name of the called
library function is given by <var class="var">fun</var>.  The hook should return an RTX
representing the place where the library function result will be returned.
</p>
<p>If this hook is not defined, then LIBCALL_VALUE will be used.
</p></dd></dl>

<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-FUNCTION_005fVALUE_005fREGNO_005fP"><span class="category-def">Macro: </span><span><strong class="def-name">FUNCTION_VALUE_REGNO_P</strong> <var class="def-var-arguments">(<var class="var">regno</var>)</var><a class="copiable-link" href="#index-FUNCTION_005fVALUE_005fREGNO_005fP"> &para;</a></span></dt>
<dd><p>A C expression that is nonzero if <var class="var">regno</var> is the number of a hard
register in which the values of called function may come back.
</p>
<p>A register whose use for returning values is limited to serving as the
second of a pair (for a value of type <code class="code">double</code>, say) need not be
recognized by this macro.  So for most machines, this definition
suffices:
</p>
<div class="example smallexample">
<pre class="example-preformatted">#define FUNCTION_VALUE_REGNO_P(N) ((N) == 0)
</pre></div>

<p>If the machine has register windows, so that the caller and the called
function use different registers for the return value, this macro
should recognize only the caller&rsquo;s register numbers.
</p>
<p>This macro has been deprecated.  Use <code class="code">TARGET_FUNCTION_VALUE_REGNO_P</code>
for a new target instead.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fFUNCTION_005fVALUE_005fREGNO_005fP"><span class="category-def">Target Hook: </span><span><code class="def-type">bool</code> <strong class="def-name">TARGET_FUNCTION_VALUE_REGNO_P</strong> <code class="def-code-arguments">(const unsigned int <var class="var">regno</var>)</code><a class="copiable-link" href="#index-TARGET_005fFUNCTION_005fVALUE_005fREGNO_005fP"> &para;</a></span></dt>
<dd><p>A target hook that return <code class="code">true</code> if <var class="var">regno</var> is the number of a hard
register in which the values of called function may come back.
</p>
<p>A register whose use for returning values is limited to serving as the
second of a pair (for a value of type <code class="code">double</code>, say) need not be
recognized by this target hook.
</p>
<p>If the machine has register windows, so that the caller and the called
function use different registers for the return value, this target hook
should recognize only the caller&rsquo;s register numbers.
</p>
<p>If this hook is not defined, then FUNCTION_VALUE_REGNO_P will be used.
</p></dd></dl>

<dl class="first-deffn first-defmac-alias-first-deffn">
<dt class="deffn defmac-alias-deffn" id="index-APPLY_005fRESULT_005fSIZE"><span class="category-def">Macro: </span><span><strong class="def-name">APPLY_RESULT_SIZE</strong><a class="copiable-link" href="#index-APPLY_005fRESULT_005fSIZE"> &para;</a></span></dt>
<dd><p>Define this macro if &lsquo;<samp class="samp">untyped_call</samp>&rsquo; and &lsquo;<samp class="samp">untyped_return</samp>&rsquo;
need more space than is implied by <code class="code">FUNCTION_VALUE_REGNO_P</code> for
saving and restoring an arbitrary return value.
</p></dd></dl>

<dl class="first-deftypevr">
<dt class="deftypevr" id="index-TARGET_005fOMIT_005fSTRUCT_005fRETURN_005fREG"><span class="category-def">Target Hook: </span><span><code class="def-type">bool</code> <strong class="def-name">TARGET_OMIT_STRUCT_RETURN_REG</strong><a class="copiable-link" href="#index-TARGET_005fOMIT_005fSTRUCT_005fRETURN_005fREG"> &para;</a></span></dt>
<dd><p>Normally, when a function returns a structure by memory, the address
is passed as an invisible pointer argument, but the compiler also
arranges to return the address from the function like it would a normal
pointer return value.  Define this to true if that behavior is
undesirable on your target.
</p></dd></dl>

<dl class="first-deftypefn">
<dt class="deftypefn" id="index-TARGET_005fRETURN_005fIN_005fMSB"><span class="category-def">Target Hook: </span><span><code class="def-type">bool</code> <strong class="def-name">TARGET_RETURN_IN_MSB</strong> <code class="def-code-arguments">(const_tree <var class="var">type</var>)</code><a class="copiable-link" href="#index-TARGET_005fRETURN_005fIN_005fMSB"> &para;</a></span></dt>
<dd><p>This hook should return true if values of type <var class="var">type</var> are returned
at the most significant end of a register (in other words, if they are
padded at the least significant end).  You can assume that <var class="var">type</var>
is returned in a register; the caller is required to check this.
</p>
<p>Note that the register provided by <code class="code">TARGET_FUNCTION_VALUE</code> must
be able to hold the complete return value.  For example, if a 1-, 2-
or 3-byte structure is returned at the most significant end of a
4-byte register, <code class="code">TARGET_FUNCTION_VALUE</code> should provide an
<code class="code">SImode</code> rtx.
</p></dd></dl>

</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Aggregate-Return.html">How Large Values Are Returned</a>, Previous: <a href="Register-Arguments.html">Passing Arguments in Registers</a>, Up: <a href="Stack-and-Calling.html">Stack Layout and Calling Conventions</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
